Maps a keyboard combination from the event structure to the keyboard equivalent of a menu item in a menu in the current menu list.

UInt32 MenuEvent (
    const EventRecord *inEvent
);

inEvent

A pointer to the event structure containing the keyboard equivalent.

function result

A value that indicates the menu ID and menu item that the user chose. If the given character does not map to an enabled menu item in the current menu list, MenuEvent returns 0 in its high-order word and the low-order word is undefined.

DISCUSSION

When the Appearance Manager is available, your program should call the MenuEvent function instead of the MenuKey function. MenuEvent maps the keyboard equivalent character in the event structure to its corresponding menu and menu item. Unlike MenuKey, the MenuEvent function supports the Shift, Option, and Control modifier keys in addition to the Command key.

The MenuEvent function does not distinguish between uppercase and lowercase letters. This allows a user to invoke a keyboard equivalent command, such as the Copy command, by pressing the Command key and “c” or “C”. For consistency between applications, you should define the keyboard equivalents of your commands so that they appear in uppercase in your menus.

If the given character maps to an enabled menu item in the current menu list, MenuEvent highlights the menu title of the chosen menu, returns the menu ID in the high-order word of its function result, and returns the chosen menu item in the low-order word of its function result. After performing the chosen task, your application should unhighlight the menu title using the HiliteMenu function.

You should not define menu items with identical keyboard equivalents. The MenuEvent function scans the menus from right to left and the items from top to bottom. If you have defined more than one menu item with identical keyboard equivalents, MenuEvent returns the first one it finds.

The MenuEvent function first searches the regular portion of the current menu list for a menu item with a keyboard equivalent matching the given key. If it doesn’t find one there, it searches the submenu portion of the current menu list. If the given key maps to a menu item in a submenu, MenuEvent highlights the menu title in the menu bar that the user would normally pull down to begin traversing to the submenu. Your application should perform the desired command and then unhighlight the menu title.

You shouldn’t assign a Command–Shift–number key sequence to a menu item as its keyboard equivalent; Command–Shift–number key sequences are reserved for use as 'FKEY' resources. Command–Shift–number key sequences are not returned to your application, but instead are processed by the Event Manager. The Event Manager invokes the 'FKEY' resource with a resource ID that corresponds to the number that activates it.

VERSION NOTES

This function is available with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when CarbonLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by CarbonLib 1.0 and later.

© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)